---
title: Provider Options
sidebar_label: Provider Options
---

Inside the [`provider.yaml`](./quickstart.mdx#provideryaml), you can specify options
that DevPod can pass to the provider when calling it.
Each option will be passed as an environment variable to the commands or can be used directly inside the `agent` section of a provider.

```yaml
...
...
options:
  MY_OPTION_NAME:
    description: "this is my option"
    default: "default_value"
    required: false
    password: true
...
...
```

## How options work

Options are variables needed for the provider to function properly, for example:

- User Accounts
- VMs images
- VMs sizes
- Account region

These options are parsed and validated by DevPod when [Adding the provider](../managing-providers/add-provider.mdx)
and passed to the provider as **environment variables**.

It's the provider's job to retrieve them from the environment and validate them.
It's recommended to make use of the `init` command that will be called by DevPod when options change to validate environment variables on the provider side.

You can check our example in the [Devpod's AWS Provider](https://github.com/loft-sh/devpod-provider-aws/blob/main/pkg/options/options.go#L44)
where we parse and validate the variables:

```go
...
    diskSizeGB, err := fromEnvOrError("AWS_DISK_SIZE")
    if err != nil {
        return nil, err
    }

    retOptions.DiskSizeGB, err = strconv.Atoi(diskSizeGB)
    if err != nil {
        return nil, err
    }
...
```

Options will also be passed to the agent and can be used in the `agent.exec` section. This is very useful if you require certain information on the agent side to perform an auto-inactivity timeout.

### Option configuration

Each option has a set of attributes that can modify how DevPod interprets it when
configuring or adding the provider:

- `description`: Description shown in `devpod provider options` and in the Desktop App
- `default`: Default value of the option provided as a string. Can also reference other variables, e.g. `${MY_OTHER_VAR}-suffix`
- `required`: Boolean if this option needs to be non-empty before using the provider. DevPod will ask in the CLI and make sure that this option is filled in the Desktop application.
- `password`: Boolean to indicate this is a sensitive value. Prevents this value from showing up in the `devpod provider options` command and will be a password field in the Desktop application.
- `suggestions`: An array of suggestions for this option. Will be shown as auto complete options in the DevPod desktop application
- `command`: A command to retrieve the option value automatically. Can also reference other variables in the command, e.g. `echo ${MY_OTHER_VAR}-suffix`. For compatibility reasons, this command will be executed in an emulated shell on Windows.
- `local`: If true, the option will be filled individually for each machine / workspace
- `global`: If true, the option will be reused for each machine / workspace
- `cache`: If non-empty, DevPod will re-execute the command after the given timeout. E.g. if this is 5m, DevPod will re-execute the command after 5 minutes to re-fill this value. This is useful if you want to store a token or something that expires locally in a variable.
- `hidden`: If true, DevPod will not show this option in the Desktop application or through `devpod provider options`. Can be used to calculate variables internally or save tokens or other things internally.

### Default values

As the name implies, this is a default value for the option. It is always advisable
to place a sensible default for any option.

You can also reference other options inside the default value, e.g. `${MY_OTHER_VAR}-suffix`. DevPod will automatically figure out what options need to be resolved before this option.

**If not specified, it defaults to an empty string**.

### Required options

If an option is required, and no default is set, DevPod will prompt the user for
a value when adding the provider.

In the DevPod Desktop App, the required options will be displayed and prompted
right in the Provider's "Add" page.

**If not specified, it defaults to false**.

### Password options

If specified and true, the option's value will be treated as a secret, so it
won't be shown when listing options.

Example:

```sh
~$ adevpod provider options civo

          NAME            | REQUIRED |          DESCRIPTION           |               DEFAULT                |                VALUE
----------------------------+----------+--------------------------------+--------------------------------------+---------------------------------------
AGENT_PATH                | false    | The path where to inject the   | /var/lib/toolbox/devpod              | /var/lib/toolbox/devpod
                          |          | DevPod agent to.               |                                      |
CIVO_API_KEY              | true     | The civo api key to use        |                                      | ********
CIVO_DISK_IMAGE           | false    | The disk image to use.         | d927ad2f-5073-4ed6-b2eb-b8e61aef29a8 | d927ad2f-5073-4ed6-b2eb-b8e61aef29a8

...
```

**If not specified, it defaults to false**.

### Options suggestions

Suggestions are a list of possible values for the option. Suggested use-cases
could be for regions/locations, VM sizes, etc...

:::info
This option is specifically for the DevPod desktop application, suggestions won't
be shown in the CLI app.
:::

**If not specified, it defaults to empty and ignored**.

### Command options

The command option lets you define a possible value for an option based on a shell
command launched on your machine. Can also reference other variables in the command, e.g. `echo ${MY_OTHER_VAR}-suffix`. For compatibility reasons, this command will be executed in an emulated shell on Windows.

One example would be to forward ENV variables from your machine to the provider,
for example:


```yaml
  AWS_ACCESS_KEY_ID:
    description: The aws access key id
    required: false
    command: printf "%s" "${AWS_ACCESS_KEY_ID:-}"
  AWS_SECRET_ACCESS_KEY:
    description: The aws secret access key
    required: false
    command: printf "%s" "${AWS_SECRET_ACCESS_KEY:-}"
```

Or running an helper command (defined in the binaries section), and forwarding the result as the option's value:

```yaml
  AWS_TOKEN:
    local: true
    hidden: true
    cache: 5m
    description: "The AWS auth token to use"
    command: |-
      ${AWS_PROVIDER} token
```

**If not specified, it defaults to empty and ignored**.

## Built-In Options

There are a couple of predefined options from DevPod, that can be used within the default field of another option or in an option command. Some built-in options are only available for `local` options as the `MACHINE_ID` might not be available already.
Predefined options:
- **DEVPOD**: Absolute path to the current DevPod CLI binary. Can be used to call a helper function within DevPod or any other DevPod command. Also available on the agent side.
- **DEVPOD_OS**: Current Operating system. Can be either: linux, darwin or windows
- **DEVPOD_ARCH**: Current operating system architecture. Can be either: amd64 or arm64.
- **MACHINE_ID**: The machine id that should be used. (Only available for local options, commands and machine providers)
- **MACHINE_FOLDER**: The machine folder that can be used to cache information locally. (Only available for local options, commands and machine providers)
- **MACHINE_CONTEXT**: The DevPod context this machine was created in. (Only available for local options, commands and machine providers)
- **MACHINE_PROVIDER**: The provider name that was used to create this machine. (Only available for local options, commands and machine providers)
- **WORKSPACE_ID**: The workspace id that should be used. (Only available for local options, commands and non-machine providers)
- **WORKSPACE_FOLDER**: The workspace folder that can be used to cache information locally. (Only available for local options, commands and non-machine providers)
- **WORKSPACE_CONTEXT**: The DevPod context this workspace was created in. (Only available for local options, commands and non-machine providers)
- **WORKSPACE_PROVIDER**: The provider name that was used to create this workspace. (Only available for local options, commands and non-machine providers)
- **PROVIDER_ID**: The provider name. (Only available for local options, commands and non-machine providers)
- **PROVIDER_CONTEXT**: The provider context. (Only available for local options, commands and non-machine providers)
- **PROVIDER_FOLDER**: The provider folder where the provider config is saved in, can be used to save global information about the provider such as global session tokens etc. (Only available for local options, commands and non-machine providers)

## Option Groups

:::info
This section is specifically for organizing options in the DevPod Desktop app.
This has no effect on the CLI app.
:::

You can organize your options in groups, for example:

```yaml
optionGroups:
  - options:
      - AWS_ACCESS_KEY_ID
      - AWS_SECRET_ACCESS_KEY
      - AWS_AMI
      - AWS_DISK_SIZE
      - AWS_INSTANCE_TYPE
      - AWS_VPC_ID
    name: "AWS options"
    defaultVisible: true
  - options:
      - AGENT_PATH
      - INACTIVITY_TIMEOUT
      - INJECT_DOCKER_CREDENTIALS
      - INJECT_GIT_CREDENTIALS
    name: "Agent options"
    defaultVisible: false
```

Options are easily grouped by listing them, each group has a `name` and a
`defaultVisible` property, which is **false by default**.
If `defaultVisible` is false, then an user will need to manually expand the option
group in the Desktop App.
